Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs_site/examples/index.md`:
- Line 123: Update the "Outputs:" line so it clearly marks coloc results as
conditional on providing allpairs inputs: change the Outputs list (the line
beginning "**Outputs:**") to indicate that "coloc results (TSV)" are only
produced if the allpairs inputs are passed (for example add "(if allpairs inputs
provided)" or similar wording next to "coloc results (TSV)") so readers don’t
assume coloc is always generated.

In `@docs_site/tools/qtlcascade.md`:
- Line 108: Several fenced code blocks in qtlcascade.md are missing language
identifiers (causing markdownlint MD040); update each untagged triple-backtick
block (the occurrences around the visible code fences) to include an appropriate
language tag (e.g., ```bash for shell/command blocks, ```text for
pseudo-formula/text blocks, ```python for Python snippets) so every ``` fence in
the file is changed to a tagged form (e.g., ```text, ```bash, or ```python) to
satisfy linting and ensure consistent rendering.
- Line 247: The table cell for `attenuation_ratio` contains raw pipe characters
which break Markdown table columns; update the description in the
`attenuation_ratio` cell (currently "1 - |pQTL_beta|/|eQTL_beta| (eqtl_mediated
only)") by escaping the inner pipe characters (e.g., replace
`|pQTL_beta|/|eQTL_beta|` with `\|pQTL_beta\|/\|eQTL_beta\|`) so the table
renders correctly.

In `@hvantk/commands/qtlcascade_cli.py`:
- Around line 248-250: The dry-run branch calls pipeline.show_plan() but
discards its return value, so nothing is printed; capture the returned formatted
plan from pipeline.show_plan() and output it (e.g., via click.echo or printing)
before returning so `hvantk qtlcascade run --dry-run` actually displays the
plan; update the block that checks dry_run to assign plan = pipeline.show_plan()
and echo/log that plan (use the CLI's existing echo/logger mechanism).

In `@hvantk/ptm/plot.py`:
- Around line 146-161: The displayed CI string uses a Unicode EN DASH between
result.enrichment_ci_low and ci_hi_str inside the ax1.text call; replace that
character with the ASCII hyphen-minus '-' in the f-string (the ax1.text block
that references ci_hi_str, result.enrichment_ci_low, and
result.enrichment_odds_ratio) so the confidence interval is rendered as
f"({result.enrichment_ci_low:.2f}-{ci_hi_str})" to avoid encoding issues.

In `@hvantk/qtlcascade/cascade.py`:
- Around line 77-104: The join currently only keys on (locus, alleles, gene_id)
so when no tissue filter is passed rows from different tissues collapse; fix by
including tissue in the join key whenever the tables contain a tissue column and
the caller did not supply a single tissue: detect if "tissue" in
list(eqtl_ht.row) or "tissue" in list(pqtl_ht.row) and if tissue is None, call
key_by/key on both eqtl_ht and pqtl_ht to include tissue (e.g., key_by(locus,
alleles, gene_id, tissue)) before performing ht = eqtl_ht.join(pqtl_ht,
how="outer"); alternatively raise a clear error requiring the tissue argument if
you prefer to force single-tissue inputs.

In `@hvantk/qtlcascade/coloc.py`:
- Around line 208-227: The join currently performed by eqtl_sel.join(pqtl_sel,
how="inner") can mix rows from different tissues when tissue is not provided;
update the logic so that if the tables contain a "tissue" field (check "tissue"
in list(eqtl_ht.row) and list(pqtl_ht.row)) you add tissue to the selected
fields (e.g., include tissue in eqtl_sel and pqtl_sel) and include tissue in the
join key, otherwise raise or require the tissue argument; modify the code around
eqtl_sel, pqtl_sel and the joined assignment to either require tissue or join on
(locus/position, alleles, gene_id, tissue) so rows from different tissues are
never merged.

In `@hvantk/qtlcascade/constants.py`:
- Around line 77-78: PQTL_SOURCES currently advertises multiple backends but
create_pqtl_tb raises NotImplementedError for all but gtex_fang; update the
constant to only list implemented backends (keep PQTL_SOURCES = ("gtex_fang",))
or split into two constants (e.g., PQTL_SOURCES_IMPLEMENTED and
PQTL_SOURCES_PLANNED) and update any CLI/help references to use the implemented
list; locate the PQTL_SOURCES definition in constants.py and the create_pqtl_tb
function in hvantk/tables/table_builders.py to ensure they are consistent.

In `@hvantk/qtlcascade/gene_summary.py`:
- Around line 91-97: After reading constraint_ht in gene_summary.py, validate
its key fields and types before calling constraint_ht.index(gene_ht.gene_id):
check that constraint_ht.key_fields (or constraint_ht.key) contains "gene_id"
and that the key field type matches the type of gene_ht.gene_id; if not, log an
error (including actual key fields and types) and raise or return early to avoid
silent missing lookups or TableIndexKeyError. Also wrap the .index(...) call in
a try/except for TableIndexKeyError to produce a clear error message referencing
constraint_ht and gene_ht rather than letting the raw exception propagate.
Ensure you update the constraint_idx/oe_lof_upper annotation only after
successful validation.

In `@hvantk/qtlcascade/pipeline.py`:
- Around line 209-217: The gene-summary is built before coloc runs so
result.coloc_df remains None; change the stage ordering to run
_stage_coloc(result, tissue) before _stage_gene_summary(result, tissue_dir) (or
alternatively call _stage_gene_summary again after _stage_coloc to merge coloc
into the summary); apply the same fix for the later block that mirrors lines
316-323 so any path that enables coloc populates result.coloc_df before
_stage_gene_summary is invoked.
- Around line 219-220: The single-tissue run path never generates the HTML
report because generate_report() is only called from run_collection(); ensure
report generation is invoked for the single-sample/run() path by calling
generate_report(...) at the end of the normal run flow (or by updating
_stage_outputs(result, safe_name) to call generate_report when appropriate).
Specifically, add a call to generate_report within run() after _stage_outputs
(or inside _stage_outputs when safe_name/result indicate single-tissue mode) so
that functions generate_report and _stage_outputs both produce the HTML report
for non-collection runs just like run_collection() does.
- Around line 339-345: The code currently filters the cascade table at
ht.filter(ht.cascade_class == "eqtl_mediated") when building cascade_genes,
which excludes genes labeled "discordant" that also have both eQTL and pQTL
signals; update the filter to include both classes (e.g., ht.cascade_class ==
"eqtl_mediated" or ht.cascade_class == "discordant", or use
hl.set(['eqtl_mediated','discordant']).contains(ht.cascade_class)) so
cascade_genes (derived from result.cascade_ht_path / ht.aggregate /
hl.agg.collect_as_set) includes discordant genes too.

In `@hvantk/qtlcascade/plot.py`:
- Around line 126-138: The empty-data branch currently returns a placeholder
figure without saving it, so downstream consumers miss the expected PNG; modify
the branch where both.empty is True to call the module's saving helper (e.g.,
_save_figure or whatever save routine is used elsewhere) with the created fig
and output_path before returning; ensure you pass the same figsize/format
parameters used elsewhere and keep the logger.warning and "No data" text, then
return the saved fig so the output_path file exists for report assembly.

In `@hvantk/qtlcascade/report.py`:
- Around line 89-96: Escape all user/data-derived strings before inserting into
HTML: import html and wrap values like tissues items, title, description, plot
names, TSV cell values, and any variables used in rows.append (e.g., tissues,
cls, cnt, pct, and other interpolated variables in the blocks at lines ~135-145,
181-185, 213-242) with html.escape(...). Update the code paths that build HTML
rows (the rows.append calls shown and similar ones elsewhere) to call
html.escape on each non-markup value and format numbers separately (don’t escape
numeric formatting), ensuring you escape join elements (e.g., ',
'.join(html.escape(t) for t in tissues)) and any string inserted into table
cells.

In `@hvantk/tables/table_builders.py`:
- Around line 1820-1839: The pQTL builder currently falls back to raw gene
symbols when gene_map_ht is omitted, which will prevent cascade joins because
create_eqtl_tb keys by Ensembl gene_id; change the logic in the block that uses
gene_map_ht so that if gene_map_ht is None you either raise a clear exception
(e.g., ValueError) requiring a gene_map_ht for cascade-compatible pQTL tables or
require an explicit opt-out flag (add a parameter like
allow_raw_gene_symbol=False) and only permit the fallback when that flag is set
true; update the code paths around gene_map_ht, ht.annotate(gene_id=...) and the
final ht.key_by("locus","alleles","gene_id") to enforce this check and surface a
helpful error message mentioning create_eqtl_tb and the cascade key tuple.

---

Outside diff comments:
In `@hvantk/tests/test_ptm.py`:
- Around line 224-233: Update the test_ptm_build_config_validation to use the
pytest tmp_path fixture instead of hardcoded "/tmp/test" strings: add tmp_path
as a test parameter, set output_dir to str(tmp_path) (or tmp_path.as_posix())
and output_ht to str(tmp_path / "out.ht") when constructing PTMBuildConfig
(refer to PTMBuildConfig and config2 in the test), so the test uses an
ephemeral, OS-independent directory and file path.

---

Nitpick comments:
In `@hvantk/commands/ptm_cli.py`:
- Line 191: The duplicate import of hail inside the ptm_annotate try block
should be removed: there is already an import hail earlier in that same try
(around Line 180), so delete the redundant "import hail" statement at the later
occurrence to avoid duplicate imports and improve clarity in the ptm_annotate
function/block.

In `@hvantk/data/gencc_streamer.py`:
- Around line 274-276: The logger.info call currently uses two adjacent
f-strings; replace them with a single f-string in the logger.info(...)
invocation so the message reads in one formatted string referencing len(genes)
and min_submitters (e.g., inside the same f-string), keeping the call to
logger.info and the variables genes and min_submitters unchanged for
readability.

In `@hvantk/datasets/uniprot_ptm_datasets.py`:
- Line 323: Replace the explicit str(e) conversion inside the f-string with the
f-string conversion flag {e!s} on the raise RuntimeError line (i.e., change
raise RuntimeError(f"Failed to download UniProt PTM data: {str(e)}") from e to
use {e!s}) so the exception text uses the explicit f-string conversion and
satisfies RUF010; keep the "from e" chaining intact.

In `@hvantk/ptm/plot.py`:
- Around line 120-140: The zip() calls iterating over bars_p/path_counts and
bars_b/benign_counts should be made strict to catch future length mismatches;
update the two zip(...) calls to use zip(..., strict=True) when iterating in the
loops that call ax1.text (referencing symbols bars_p, path_counts, bars_b,
benign_counts) so a ValueError is raised if lengths differ.

In `@hvantk/qtlcascade/__init__.py`:
- Around line 76-113: The __all__ export list is unsorted which triggers RUF022;
sort the entries in the __all__ list (e.g., "build_cascade",
"build_cascade_gene_summary", "CASCADE_CLASS_COLORS", "CASCADE_CLASSES",
"CascadeConfig", "CascadePipeline", "CascadeResult",
"DEFAULT_COLOC_H4_THRESHOLD", etc.) into a stable lexicographic order (or
replace with a manually sorted static ordering) so the list is deterministic and
lint-stable; update the existing __all__ definition accordingly while preserving
all original names.

In `@hvantk/qtlcascade/gene_summary.py`:
- Around line 75-76: The conditional checking "gene_symbol" in row_fields inside
gene_summary (the agg_exprs["gene_symbol"] = hl.agg.take(ht.gene_symbol, 1)[0]
branch) is dead with the current cascade builder (see build_cascade in
cascade.py not emitting gene_symbol); either remove the unreachable conditional
and associated agg_expr, or keep it but add a brief clarifying comment above
referencing build_cascade and that this is intentional defensive/future-proofing
for external cascades/schema changes so reviewers understand it is deliberate.
Ensure the comment names the symbols row_fields, agg_exprs, gene_symbol, and
build_cascade to make the rationale discoverable.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@hvantk/ptm/plot.py`:
- Around line 120-139: Update the two zip calls in hvantk/ptm/plot.py to use
strict matching: replace zip(bars_p, path_counts) with zip(bars_p, path_counts,
strict=True) and zip(bars_b, benign_counts) with zip(bars_b, benign_counts,
strict=True) so the loops that call ax1.text(...) on bars_p/path_counts and
bars_b/benign_counts explicitly enforce equal lengths and satisfy Ruff B905.

In `@hvantk/qtlcascade/pipeline.py`:
- Around line 464-467: The report currently collects all PNGs from the shared
plots directory via self._plots_dir.glob("*.png"), causing stale images from
other runs to appear; change plot discovery in the plot_paths construction (and
the similar block around lines 510-513) to only include images produced by the
current run—e.g., restrict the glob or filter by the current run
identifier/output directory used when saving plots (use self.output_dir or
self.run_id / run_name as a prefix or parent directory) so plot_paths only
contains files belonging to this invocation.
- Around line 201-202: The sanitized tissue slug produced by _sanitize() is
lossy and can collide (e.g., "Brain/Cortex" vs "Brain Cortex"), causing
tissue_dir and plot filenames to overwrite; update the code in run and
run_collection to derive a stable, unique slug from tissue_label by combining
the sanitized name with a short deterministic suffix (e.g., first 8 chars of a
hash or base64 digest of tissue_label) and use that single unique_slug for
per_tissue paths and plot filenames (replace uses of safe_name with unique_slug
for tissue_dir and any plots/<slug>_* generation, including the other
occurrences around the 245-253 and 539-543 regions) so distinct tissues never
collapse to the same output path.
- Around line 459-462: The try/except around hl.read_table(...).to_pandas()
silently swallows failures (setting gene_df to None) — change the except to
catch Exception as e, log a clear error including result.gene_summary_ht_path
and the exception details (e) via the module logger (or raise a new RuntimeError
with that context) and then either re-raise so report generation fails fast or
explicitly mark the report as failed; apply the same change to the other
identical block that reads the gene summary (the block using
hl.read_table(...).to_pandas() and gene_df).
- Around line 329-331: _in _stage_gene_summary(), gene_ht.export(tsv_path) does
not honor self.config.overwrite, causing inconsistent rerun behavior; modify the
code around the export so that before calling gene_ht.export(tsv_path) you check
self.config.overwrite and if true remove any existing tsv_path (use the
appropriate filesystem removal for your execution environment: local os.remove
or cloud/hadoop rm via hail/utils or subprocess), and if overwrite is false and
tsv_path already exists raise/exit with a clear error; do this adjacent to the
existing call sites _stage_gene_summary, build_cascade_gene_summary, and the
tissue_dir/gene_summary.tsv path to ensure consistent behavior.

In `@hvantk/tables/table_builders.py`:
- Around line 1507-1526: _scan_tissue_files currently uses pathlib.Path and will
fail for cloud URIs (gs://, s3://); replace the Path-based logic with a
cloud-aware filesystem like hailtop.fs (or hailtop.fs.get_fs) similar to
_cleanup_temp_file: detect cloud URIs (e.g., input_path.startswith("gs://") or
"s3://"), use the filesystem client to check existence and file/dir semantics,
list matching files using the fs.glob or fs.ls APIs for each extension, and
build the [(file_path, tissue_name)] list by extracting the filename stem (split
on "/" then split basename on "." to get the tissue prefix) so both local and
cloud paths are supported by _scan_tissue_files.

---

Duplicate comments:
In `@hvantk/qtlcascade/pipeline.py`:
- Around line 76-91: The validate() method must reject out-of-range thresholds
and coloc parameters: add checks in validate() to ensure eqtl_p_threshold and
pqtl_p_threshold are between 0 and 1 (exclusive of negatives or >1) and, if
present, that coloc priors (e.g., coloc_prior / coloc_prior_secondary) are >0
and <=1 and coloc window/size parameters are positive integers; append
descriptive error strings to errors when any of these constraints fail, keeping
the existing eqtl_allpairs_ht/pqtl_allpairs_ht consistency check (use the
validate() function and attribute names eqtl_p_threshold, pqtl_p_threshold,
coloc_prior, coloc_window to locate where to add the new guards).

---

Nitpick comments:
In `@hvantk/qtlcascade/coloc.py`:
- Around line 80-85: The _logdiff function can produce -inf/NaN when a <= b; add
a numerical guard at the start of _logdiff to handle that case (e.g., if a <= b
+ eps) and return -np.inf (log(0)) instead of computing np.log1p(-np.exp(b -
a)); otherwise proceed with the existing computation. Use a small epsilon (e.g.,
1e-12) to tolerate tiny rounding errors and reference the function name _logdiff
so you update that exact function.
- Around line 219-232: The code currently only logs a warning when eqtl_ht or
pqtl_ht contain a "tissue" column but no tissue parameter is provided, which
allows incorrect cross-tissue joins; change this to require an explicit tissue:
when eqtl_has_tissue or pqtl_has_tissue and tissue is falsy, raise a ValueError
(or use logger.error then raise) with a clear message instructing the caller to
provide the tissue parameter; keep the existing filtering logic that applies
eqtl_ht.filter(eqtl_ht.tissue == tissue) and pqtl_ht.filter(pqtl_ht.tissue ==
tissue) when tissue is provided (referencing eqtl_ht, pqtl_ht, and tissue), and
remove or replace the logger.warning block so the function fails fast instead of
proceeding with a risky join.

In `@hvantk/qtlcascade/plot.py`:
- Around line 338-340: The loop using zip(bp["boxes"], colors) should use
zip(..., strict=True) to defensively ensure bp["boxes"] and colors have
identical lengths; update the iteration (where bp["boxes"] and colors are
created from classes) to call zip(bp["boxes"], colors, strict=True) so any
future mismatch between bp["boxes"] and colors raises an error immediately.

In `@hvantk/tests/test_cli_qtlcascade.py`:
- Around line 76-116: Update the two tests test_run_cmd_dry_run and
test_run_cmd_single_tissue to use the pytest tmp_path fixture instead of the
hardcoded "/tmp/cascade_out": add tmp_path as a test parameter, build an output
path from tmp_path (e.g. tmp_path / "cascade_out" converted to a string) and
pass that string to the CLI args in place of "/tmp/cascade_out"; ensure both
test functions (and the runner.invoke calls) use the new tmp_path-derived path
so the tests use an isolated temporary directory.

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@hvantk/qtlcascade/pipeline.py`:
- Around line 468-472: The current code globbing self._plots_dir (using
_sanitize(result.tissue) and building plot_paths from files matching
"{safe}_*.png") can include stale images from previous runs; instead, record the
exact plot files written during this invocation on the CascadeResult (e.g.,
add/append to a result.plots list or result.plot_paths when each plot is
written) and use that list to build plot_paths; similarly, stop globbing for
"cross_tissue_heatmap.png" and read it only if it was recorded on the
CascadeResult for this run. Update the plot-writing functions to append
successful writes to the CascadeResult (unique symbols: CascadeResult,
result.plots or result.plot_paths, self._plots_dir, _sanitize,
cross_tissue_heatmap.png) and replace the glob-based construction with iteration
over the recorded list.
- Around line 201-202: The current use of _sanitize(tissue_label) is lossy and
can collapse distinct labels (e.g. "Brain/Cortex" vs "Brain Cortex"); replace
ad-hoc calls with a single-run mapping that generates a collision-resistant slug
per tissue_label (e.g. sanitized base plus a short deterministic hash or UUID
derived from the original tissue_label) and reuse that slug wherever safe_name
or tissue_dir and plot prefixes are produced (locations using _sanitize,
including the code that sets safe_name and tissue_dir and the later usages
around the plot prefix code). Implement a map on the pipeline instance (e.g.
self._tissue_slug_map) populated once when tissues are enumerated and then
reference self._tissue_slug_map[tissue_label] instead of calling _sanitize
directly. Ensure the slug remains stable for the duration of the run and is used
for per-tissue directories and plot prefixes.
- Around line 329-331: The export step ignores self.config.overwrite: before
calling gene_ht.export(tsv_path) check whether the destination exists and honor
self.config.overwrite — if overwrite is true, remove the existing tsv (and any
related compressed variant) using the appropriate filesystem helper (Hail's
hadoop utilities for remote paths or os.unlink for local paths), and if
overwrite is false and the file exists, raise or fail early with a clear
message; then call gene_ht.export(tsv_path). Reference gene_ht, export(),
tsv_path, tissue_dir and self.config.overwrite to locate where to add the
existence check and deletion.